Internationalization/Technical/Best practices
Changing existing messages * Consider updating the message documentation * If old translations are not suitable for the new meaning you SHOULD change the message key. This also includes changes in message handling (parsing, escaping). * Please only change the English source message and/or key. The rest will be updated by translators. This also applies when you're only changing things like HTML tags that you could change in other languages without speaking those languages. Remove unused messages Messages are constantly being translated to new languages (some of which you have never even heard of before). If you leave a message that is no longer used or displayed anywhere inside the .i18n.php file, translators will lose their time working on useless messages. You MUST remove messages from .i18n.php when you remove them from the rendering code. As with changing existing messages, you only need to remove the EN version. Capitalization As described in design & copy i18n manual, if you really need to emphasise something with capitals, use CSS styles to do so. HTML attributes style="text-transform:uppercase" (uppercase) or style="font-variant:small-caps" (Small Caps) will do. Since these may be adjusted to something else during translation, most specifically for non-Latin scripts, they need to be part of the messages and must not be added programmatically. Emphasis In normal text, emphasis like boldface or italics and similar should be part of message texts. Local conventions on emphasis often vary, especially some Asian scripts have their own. Translators must be able to adjust emphasis to their target languages and areas. Avoid patchwork messages Languages have varying word orders, and complex grammatical and syntactic rules. Messages put together from lots of pieces of text, possibly with some indirection, are very hard, if not impossible, to translate. Better make messages complete sentences each, with a full stop at the end. Several sentences can usually much more easily be combined into a text block, if needed. Example Consider the following example (message values are given as comments): :$h = 10; :$msg = wfMsg( 'no-of-hours', $h ) /* $1 */ . wfMsg( 'hours' ) /* hours */ . wfMsg( 'ago' ) /* ago */; This might work for English, but will likely not work for a whole lot of other languages. That's because the word order here is fixed -- German, for example, would have to have ago $1 hours, which is not possible with this code. The right way to handle this is: :$msg = wfMsg( 'hours-ago', $h ); /* $1 hours ago */ Always use a single message instead of a few in consecutive order, unless you have a very good reason not to. Messages quoting each other An exception from the rule may be messages referring to one another: Enter the original authors name in the field labelled ''" "' and click " " when done.'' It is safe when a wiki operator alters the messages "name" or "proceed". Without the int-hack, operators would have to be aware of all related messages needing adjustment, when they alter one. One sentence per line Try to have one sentence or similar block in one line. This helps to compare the messages in different languages, and may be used as an hint for segmentation and alignment in translation memories. Be aware of whitespace and line breaks MediaWiki's localized messages usually get edited within the wiki, either by admins on live wikis or by the translators on translatewiki.net. You should be aware of how whitespace, especially at the beginning or end of your message, will affect editors: * Newlines at the beginning or end of a message are fragile, and will be frequently removed by accident. Start and end your message with active text; if you need a newline or paragraph break around it, your surrounding code should deal with adding it to the returned text. * Spaces at the beginning or end of a message are also likely to end up being removed during editing, and should be avoided. If a space is required for output, usually your code should be appending it or else you should be using a non-breaking space such as (in which case check your escaping settings!) * Try to use literal newlines rather than "\n" characters in the message files; while \n works in double-quoted strings, the file will be formatted more consistently if you stay literal. Avoid untranslated HTML markup in messages HTML markup not requiring translation, such as enclosing s, rulers above or below, and similar, should usually better not be part of messages. They unnecessarily burden translators, increase message file size, and pose the risk to accidentally being altered in the translation process.